//! 双端队列核心类型定义模块

use std::collections::VecDeque;

/// 泛型双端队列结构体
///
/// 使用标准库VecDeque作为底层实现，支持O(1)时间复杂度的首尾操作
/// 通过泛型参数T实现类型安全，避免原始指针的使用
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct Queue<T> {
    inner: VecDeque<T>,
}

impl<T> Queue<T> {
    /// 构造空队列实例
    ///
    /// # 返回值
    /// 返回初始化完成的队列实例
    pub fn new() -> Self {
        Self {
            inner: VecDeque::new(),
        }
    }

    /// 在队列头部插入新元素
    ///
    /// # 参数
    /// - `data`: 要插入队列头部的元素
    ///
    /// # 返回值
    /// 总是返回成功（VecDeque的push_front不会失败）
    pub fn push_head(&mut self, data: T) {
        self.inner.push_front(data);
    }
    /// 判断队列是否为空
    ///
    /// # 参数
    /// - `&self`: 队列的不可变借用
    ///
    /// # 返回值
    /// 返回`true`表示队列为空，`false`表示有元素
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }

    /// 在队列尾部插入元素
    ///
    /// # 参数
    /// - `item`: 要插入的泛型元素
    ///
    /// # 注意
    /// 使用VecDeque的push_back实现，保证O(1)时间复杂度
    pub fn push_back(&mut self, item: T) {
        self.inner.push_back(item);
    }
}


impl<T> Queue<T> {
    /// 从队列头部移除并返回元素
    ///
    /// # 返回值
    /// 返回`Option<T>`类型：
    /// - `Some(T)` 表示成功取出头部元素
    /// - `None` 表示队列为空
    pub fn pop_head(&mut self) -> Option<T> {
        self.inner.pop_front()
    }
}

impl<T> Drop for Queue<T> {
    /// 自动释放队列内存（通过VecDeque的Drop实现）
    ///
    /// 当队列离开作用域时自动调用，无需手动释放
    /// 底层VecDeque会自动清理所有元素的内存
    fn drop(&mut self) {
        // VecDeque的Drop实现会自动处理元素释放
        // 无需显式弹出元素，内存安全由Rust保证
    }
}

impl<T> Queue<T> {
    /// 从队列尾部移除并返回元素
    ///
    /// # 返回值
    /// 返回 `Option<T>`:
    /// - `Some(T)` 当队列非空时返回被移除的元素
    /// - `None` 当队列为空时返回
    ///
    /// # 时间复杂度
    /// 保证 O(1) 时间复杂度，使用 VecDeque 的 pop_back 实现
    pub fn pop_tail(&mut self) -> Option<T> {
        self.inner.pop_back()
    }
}


impl<T> Queue<T> {
    /// 查看队列头部元素（不移除）
    ///
    /// # 参数
    /// - `&self`: 队列的不可变借用
    ///
    /// # 返回值
    /// - `Option<&T>`: 当队列不为空时返回Some(元素引用)，空队列返回None
    pub fn peek_head(&self) -> Option<&T> {
        self.inner.front()
    }

    /// 查看队列尾部元素（不移除）
    ///
    /// # 参数
    /// - `&self`: 队列的不可变借用
    ///
    /// # 返回值
    /// - `Option<&T>`: 当队列不为空时返回Some(元素引用)，空队列返回None
    pub fn peek_tail(&self) -> Option<&T> {
        self.inner.back()
    }
}